Search isn’t only about retrieving results. Sometimes, depending on what users search for, you may want to display custom data in your UI, like ads or promotional banners. For example, consider an online bookstore that wants to display a discount for users looking for Harry Potter titles. With Algolia’s Rules, they can display a banner for specific queries.

​
Algolia out-of-the-box banner solution

The easiest way to display a banner above your search results is by adding a rule with the Visual Editor in the Algolia dashboard. The rule adds data to the search response which the InstantSearch UI library uses to display the banner.
This requires either the Hits widget or InfiniteHits widget from one of the following: InstantSearch.js version 4.73.0 or later, React InstantSearch version 7.12.0 or later, or Vue InstantSearch version 4.19.0 or later.

​
Create a rule with a banner consequence in the Visual Editor

  1. Click Create your first Rule or New rule and select Visual Editor.
  2. In the It all starts here section, click Set query conditions.
  3. In the Your query input, enter harry potter and click Apply.
  4. In the What do you want to do? section, click Add Banner.
  5. Enter the required content for your banner—the URL for your banner image and click Apply.
  6. Review your banner preview now displayed above the hits.
  7. Confirm your changes by clicking Review and Publish.

​
Create a rule with a banner consequence using the API

To add a rule with a banner consequence using the API, use the saveRule method. When adding a rule, you need to define a condition and a consequence. In the consequence, add search parameters and configure renderingContent using the following template:
json
{
  "renderingContent": {
    "widgets": {
      "banners": [
        {
          "image": {
            "urls": [
              "url": "https://www.algolia.com/banner.jpg"
            ]
            title: "20% OFF on all Harry Potter books!"
          },
          "link": {
            "url": "https://www.algolia.com/harry-potter-promo",
            "target": "_blank"
          }
        }
      ]
    }
  }
}

​
Display the banner with InstantSearch

After adding the rule, you can display the banner in your UI if the renderingContent.widgets.banners property is present in the API response. You can use the Hits or InfiniteHits widgets from InstantSearch.js, React InstantSearch, or Vue InstantSearch to display the banner. The banner renders automatically unless you have configured the widget to hide it. 
<!-- Do not display the banner in the Hits widget -->
<ais-hits :showBanner="false" />

​
Custom banner solution

​
Create a rule for returning custom data

If you want to motivate users to buy Harry Potter books, you could display a special promotion banner at the top of search results whenever their search query contains “harry potter”: “20% OFF on all Harry Potter books!” For this, first need to set a rule that returns the custom data you want to display. Then, you need to display this data whenever it comes up. You can add the rule using the API or the Algolia dashboard. Then, you can activate it in your frontend code to retrieve the banner.

​
Create a rule with the API

To add a rule, you need to use the saveRule method. When setting a rule, you need to define a condition and a consequence. For the preceding example, you want to show the banner whenever the query contains “harry potter”. You don’t need it to be exact. If the query is “harry potter azkaban” or “books harry potter”, you still want to display the promotion. 
JObject data = new JObject();
data.Add("promo_content", "20% OFF on all Harry Potter books!");

var rule = new Rule
{
    ObjectID = "a-rule-id",
    Enabled = false,
    Conditions = new List<Condition>
    {
        new Condition { Anchoring = "contains", Pattern = "harry potter" }
    },
    Consequence = new Consequence { UserData = data }
};

index.SaveRule(rule);

// Asynchronous
await index.SaveRuleAsync(rule);

​
Create a rule in the dashboard

To add rules in the Algolia dashboard:
  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index:
  4. Open the Rules page in the Algolia dashboard.
  5. Select Create your first rule or New rule. In the drop-down menu, click the Manual Editor option.
  6. In the Condition(s) section, keep Query toggled on, select Contains from the drop-down menu, and enter “harry potter” in the input field.
  7. In the Consequence(s) section:
    1. Click Add consequence and select Return Custom Data.
    2. In the input field, add the data to return when a search query matches the rule: { "promo_content": "20% OFF on all Harry Potter books!" }
  8. Save your changes.

​
Duplicate rules to adapt to user search patterns

To ensure that the Samsung Galaxy Note 20 Ultra banner displays for the search term “note” in the preceding example:
  1. Duplicate the existing Samsung Galaxy Note 20 Ultra rule.
  2. Edit the rule to change the Query search phrase to “Note”.
The newly duplicated rule now matches the first precedence logic criterion (Position) and displays the desired banner.

​
Retrieve the banner data in your UI

Now that your rule is ready, you can display a banner in your search UI if the userData property is present in the API response. For example, with InstantSearch: 
<ais-query-rule-custom-data>
  <template v-slot:item="{ item }">
    <p>{{ item.promo_content }}</p>
  </template>
</ais-query-rule-custom-data>
You can learn more about this widget in the InstantSearch API reference:

​
Apply rules with context conditions

If you want to apply rules based on context, see:

​
Determining priority when you have multiple banners

You may have quite a few semi-permanent promotional banners for specific product categories, as well as some time-limited, temporary banners for certain products. For instance, an online IT hardware store has banners for the following categories:
  • Phones
  • Tablet computers
  • Laptop computers
  • Desktop computers
They also have temporary offers and associated banners for the phrases/products:
  • Huawei Honor Note 10
  • Xiaomi Redmi Note 10 Pro
  • Samsung Galaxy Note 20 Ultra
  • Samsung Galaxy Tab S7+
  • Samsung Galaxy Book Pro 360
Since Algolia can only apply one rule at a time (and, hence, display one banner), tie-breaking precedence logic is used to determine which one to use. Using the preceding example, users starts on the Phones page (and can see the appropriate banner for that), then search for “note”. For most stages, Huawei Honor Note 10, Xiaomi Redmi Note 10 Pro, and Samsung Galaxy Note 20 Ultra are tied and take precedence over the category banners. The final tie-breaking stage, invoked in this case, is rule ID: this looks for the rule with the smallest objectID, which in this case just happens to be for the Huawei Honor Note 10. Don’t assume that a rule that was created some time ago will have a smaller objectID than a more recent rule. It’s best to not rely on objectID to determine precedence but to manually set it.